---
title: "Service Name Sampler"
description: "This action is a [Service Action](/pipeline/actions/introduction#scope-categories) that samples traces based on the presence of specified services within a trace."
sidebarTitle: "Service Name Sampler"
icon: "tag"
---

import BetaWarning from '/snippets/beta-warning.mdx';
import AssumeNoMeaning from '/snippets/assume-no-meaning.mdx';

<BetaWarning />

## Considerations

<Warning>
  Before enabling the **Service Name Sampler**, please consider the following:

  - Only supports **traces**.
  - Sampling is trace-wide: either all spans in a trace are kept, or all are dropped.
  - The sampler introduces a delay of up to 30 seconds before traces are exported.
  - Traces with durations longer than 30 seconds might not be sampled correctly.
</Warning>

## Use Cases

**Targeted Trace Collection**

- Collect only traces involving specific microservices, such as `auth-service`, for debugging or focused observability.

**Cost Reduction**

- Significantly reduce collected trace volume by focusing on services that matter most.

## Configuration Options

The ServiceNameSampler action is configured using the `odigos.io/v1alpha1.Action` CRD with the `samplers` configuration section.

<AccordionGroup>
  <Accordion title="actionName">
    **actionName** `string`: A human-readable name for the action.
    - *Optional*
    - <AssumeNoMeaning />
  </Accordion>

  <Accordion title="notes">
    **notes** `string`: Free-form notes to describe the purpose or intent of this sampler.
    - *Optional*
    - <AssumeNoMeaning />
  </Accordion>

  <Accordion title="disabled">
    **disabled** `boolean`: Temporarily disables this sampler without deleting its configuration.
    - *Optional*, defaults to `false`
  </Accordion>

  <Accordion title="signals *">
    **signals** `string[]`: The signal types this action will operate on.
    - *Required*
    - Only `TRACES` is supported.
  </Accordion>

  <Accordion title="samplers *">
    **samplers** `object` : Configuration for sampling actions.
    - This field is *required* for this action type
    <AccordionGroup>
      <Accordion title="serviceNameSampler *">
        **serviceNameSampler** `object` : Configuration for the ServiceNameSampler.
        - This field is *required* for this action type
        <AccordionGroup>
          <Accordion title="services_name_filters *">
            **services_name_filters** `object[]` : An array of objects representing the filters for the services.
            - This field is *required*
            <AccordionGroup>
              <Accordion title="service_name *">
                **service_name** `string` : Specifies the service name to search within the trace (Across all available spans).
                - This field is *required*
              </Accordion>

              <Accordion title="sampling_ratio *">
                **sampling_ratio** `float` : Specifies the sample rate for all traces that contains `service_name`.
                - This field is *required*
              </Accordion>

              <Accordion title="fallback_sampling_ratio *">
                **fallback_sampling_ratio** `float` : Specifies the percentage of traces that don't meet the service name filter and that you still like to retain.
                - This field is *required*
              </Accordion>
            </AccordionGroup>
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

<Info>
  A trace is sampled if it contains **at least one span** from a service listed in `services_name_filters` and passes the `sampling_ratio` check. Traces without any listed services may still be sampled based on the corresponding `fallback_sampling_ratio`.
</Info>

## Basic Example

This example samples **100%** of traces that contain `coupon-service` and **0%** of all other traces using the new Action CRD:

<Steps>
  <Step>
    Create a YAML file with the following content:

    ```yaml service-name-sampler.yaml
    apiVersion: odigos.io/v1alpha1
    kind: Action
    metadata:
      name: coupon-service-sampler
      namespace: odigos-system
    spec:
      actionName: "coupon-sampler"
      signals:
        - TRACES
      samplers:
        serviceNameSampler:
          services_name_filters:
            - service_name: coupon-service
              sampling_ratio: 100
              fallback_sampling_ratio: 0
    ```
  </Step>
  <Step>
    Apply the sampler:

    ```bash
    kubectl apply -f service-name-sampler.yaml
    ```
  </Step>
</Steps>

## Advanced Example

This example collects:
- 100% of traces with `payment-service`
- 50% of traces with `auth-service`
- 10% of traces that include **neither** of the above

```yaml advanced-service-name-sampler.yaml
apiVersion: odigos.io/v1alpha1
kind: Action
metadata:
  name: multi-service-sampler
  namespace: odigos-system
spec:
  actionName: "multi-service-focus"
  signals:
    - TRACES
  samplers:
    serviceNameSampler:
      services_name_filters:
        - service_name: payment-service
          sampling_ratio: 100
          fallback_sampling_ratio: 10
        - service_name: auth-service
          sampling_ratio: 50
          fallback_sampling_ratio: 10
```

This setup ensures you always keep critical traces and still retain a sample of the rest for broader context.

